CHAPTER 4 CONFIGURING AND USING THE REQUESTERS Btrieve provides a DOS Requester, an OS/2 Requester, a Windows Requester, and a UnixWare Requester. This chapter provides configuration options and instructions for loading and unloading the Requester in each operating environment. NOTE: The Btrieve Requesters have changed (primarily in key definition) between previous versions and Btrieve v6.1. Therefore, all workstations accessing the Btrieve v6.1 NLM must use the Btrieve v6.1 Requesters. For information about the new UnixWare Requester, please refer to the Readme file that accompanies this release. DOS Requester You must load the Btrieve DOS Requester (BREQUEST.EXE) at a workstation running DOS before that workstation can access network Btrieve files using the Btrieve NLM. The DOS Requester loads into a DOS workstation's memory as a Terminate and Stay Resident (TSR) program. You can access local as well as remote files by running both client-based (local) Btrieve and the Requester at your workstation. NOTE: Client-based Btrieve is available only as part of the Btrieve Developer's Kit and must be purchased separately. DOS Requester Configuration Options There are five configuration options for the Btrieve DOS Requester: NetWare Runtime Server Support (/C), Data Message Length (/D), DOS Session Load (/L), Real-Time Data Compression (/O), and Help (/?). Previous versions of the DOS Requester also supported the /S and /R options. The DOS Requester v6.x accepts the /S and /R options for backwards compatibility, but otherwise ignores them. NetWare Runtime Server Support (/C) Range: None Default: /C:1 Memory Required: Not applicable This option allows you to enable or disable NetWare Runtime server support. /C:0 | /C:1 | /C:1,username,password /C:0 Disables NetWare Runtime server support. /C: Enables NetWare Runtime server support. Btrieve looks at the username for the drive (current server) on which you are presently running. If the username is SUPERVISOR, Btrieve searches for another username in the table of usernames for the servers onto which you are logged. If the username is not SUPERVISOR, Btrieve searches for that username on the NetWare Runtime server. If it is not a valid username, Btrieve returns an error at the time of the Open or Create request. /C:1,username,password Enables NetWare Runtime server support. Btrieve verifies the specified username and password for the NetWare Runtime server. Btrieve returns an error if the specified username is not found or the password is invalid. username Preferred login name on the NetWare Runtime server. If you specify SUPERVISOR for the username, Btrieve returns an error and the DOS Requester will not load. password Login password for the specified user. For information on using Btrieve with NetWare Runtime, see Chapter 3, "Installing and Configuring Btrieve." Data Message Length (/D) Range: 532 through 57,000 bytes Default: 4,096 bytes Memory Required: 538 bytes + data message length This option specifies the length of the largest record (or the largest portion or chunk of a record) you want to access through Btrieve. (If you omit this option, the Requester uses the default value, 8,192.) The Requester uses this value to calculate the length of the data message buffer reserved for passing records between Btrieve and your applications. The Requester maintains one copy of the data message buffer. The value you enter here should not exceed the largest record size you configure for Btrieve through the Setup utility since that is the maximum message that BSPXCOM can receive. (For more information, refer to the section "Largest Record Size.") Specify the data message length in bytes. For example, if the largest record your application uses is 3,000 bytes, specify the /D option as follows: /D:3000 Specifying a higher value than you need for the /D option does not improve performance and may waste memory. DOS Session Load (/L) Range: Not applicable Default: Not applicable Memory Required: Not applicable This option allows you to load another instance of BREQUEST even if it is already loaded. This option is useful if you want to run Windows applications using the DOS Requester while running DOS VM applications that are also using the DOS Requester. To run Windows applications that use the DOS Requester, you must load BREQUEST before starting Windows. In order to run DOS applications in Windows, you must load BREQUEST in each DOS session. However, if you load BREQUEST outside of Windows, you cannot load it again in a DOS session. For Windows applications using the DOS Requester, load BREQUEST outside of Windows. In each Windows DOS session that will be running a Btrieve application, load BREQUEST with the /L option. Doing so will load another instance of BREQUEST that is available only to the DOS session. This operation provides the DOS session with its own copy of BREQUEST and prevents the DOS session from using the instance of BREQUEST that you loaded before starting Windows. Real-Time Data Compression (/O) Range: None Default: No compression Memory Required: Approximately 32 KB on the workstation and 32 KB per client on the server In many cases (such as when implementing extended reads, VATs), this option can help reduce network traffic by reducing the number of packets required to complete a request to Btrieve. This option may, however, adversely affect memory and performance. Compressing and decompressing data takes extra CPU time on both the server and client sides. Because of overhead, you should not use this option with fast networks or with slow workstations for clients. Help (/?) The /? option lists the other options that are available (/C, /D, and /O) and mentions that although the /S and /R options are accepted for backwards compatibility, Btrieve v6.x ignores them. Loading the DOS Requester Load the DOS Requester at the workstation by entering the following command: [path] BREQUEST [option] path The pathname to the directory where the DOS Requester is stored. You can omit the pathname if the DOS Requester is stored on the default drive or if it is located in a directory in your search path. option Any of the configuration options (/C, /D, /L, /O, or /?). For example, if the Requester is on the default drive and you want to specify a 2,048-byte data message length, enter BREQUEST /D:2048. The forward slash (/ ) before the configuration option is the only valid character you can use. If you specify a dash (-) or a backslash ( \), the Requester may load improperly. Unloading the DOS Requester To unload the DOS Requester, use the DOS Requester utility, BREQUTIL.EXE. At the workstation where the DOS Requester is loaded, enter BREQUTIL -STOP. (To determine the version of your DOS Requester, you can enter BREQUTIL -VER.) NOTE: If files have been left open (as happens, for example, when an application does not issue a Close operation for each open file), simply logging out of one or more servers from a workstation does not close Btrieve files or terminate the Btrieve SPX connection to the server. To close Btrieve files and terminate the connection, use the BREQUTIL -STOP command. OS/2 Requester The following files must be loaded in a directory listed in an OS/2 workstationÕs LIBPATH before a Btrieve application can access the Btrieve NLM from that workstation: o BTRCALLS.DLL - the Btrieve dynamic link Requester for OS/2 workstations. o NDBCOMM.DLL - the communications Requester for OS/2 workstations. NDBCOMM.DLL provides the necessary data communications between the workstation and the Btrieve NLM. You can access local as well as remote files by running both client-based (local) Btrieve and the Requester at your workstation. If you want to run both client-based Btrieve and the Requester, you must use the OS/2 Conversion utility (NDBCNVT.EXE) to convert the client-based BTRCALLS.DLL to BTRLOCL.DLL. (By default, the Requester and client-based Btrieve have the same name.) NOTE: Client-based Btrieve is available only as part of the Btrieve DeveloperÕs Kit and must be purchased separately. OS/2 Requester Configuration Options You are not required to specify any configuration options for the OS/2 Requester. Since the internal tables that control the options are not fixed, the tables will grow as needed. There are three configuration options for the OS/2 Requester: NetWare Runtime Server Support (/C), Data Message Length (/D), and Number of Servers (/S). NOTE: Although you can set the initial size of the tables using the Data Message Length (/D) and the Number of Servers (/S) options, setting table sizes is not recommended. NetWare Runtime Server Support (/C) Range: None Default: /C:1 Memory Required: Not applicable This option allows you to enable or disable NetWare Runtime server support. /C:0 | /C:1 | /C:1,username,password /C:0 Disables NetWare Runtime server support. /C:1 Enables NetWare Runtime server support. Btrieve looks at the username for the drive (current server) on which you are presently running. If the username is SUPERVISOR, Btrieve searches for another username in the table of usernames for the servers onto which you are logged. If the username is not SUPERVISOR, Btrieve searches for that username on the NetWare Runtime server. If it is not a valid username, Btrieve returns an error at the time of the Open or Create request. /C:1,username,password Enables NetWare Runtime server support. Btrieve verifies the specified username and password for the NetWare Runtime server. Btrieve returns an error if the specified username is not found or the password is invalid. username Preferred login name on the NetWare Runtime server. If you specify SUPERVISOR for the username, Btrieve returns an error and the OS/2 Requester will not load. password Login password for the specified user. For information on using Btrieve with NetWare Runtime, see Chapter 3, "Installing and Configuring Btrieve." Data Message Length (/D) Range: 532 through 65,000 bytes Default: 4,096 bytes Memory Required: 538 bytes + data message length The /D option specifies the length of the largest record (or the largest portion or chunk of a record) you want to access through Btrieve. The OS/2 Requester uses this value to calculate the length of the data message buffer reserved for passing records between Btrieve and your applications. The Requester maintains one copy of the data message buffer. The value you enter here should not exceed the value you specified for the Largest Record Size configuration option in the Setup utility. (For more information, refer to the section "Largest Record Size.") The value for this option represents the maximum message length that BSPXCOM can receive. Specify the record length in bytes. For example, if the largest record your application uses is 3,000 bytes, specify the /D option as follows: /D:3000 Specifying a higher value than you need for the /D option does not improve performance. Number of Servers (/S) Range: 1 through 255 Default: 8 Memory Required: 27 bytes per server The /S option specifies the number of servers that have the Btrieve NLM active on the network. Configuring the OS/2 Requester Set the Requester configuration options using the following command: SET BRQPARMS=option option Any of the three configuration options (/C, /D, or /S). Do not include a space between BRQPARMS and the equal sign. You can, however, insert a space between each configuration option you specify. For example, to specify a 10,240-byte data message length and four servers, issue the following command: SET BRQPARMS=/D:10240 /S:4 The forward slash (/ ) before the configuration option is the only valid character you can use. If you specify a dash (-) or a backslash ( \), the Requester may load improperly. Loading the OS/2 Requester An application may load the Btrieve for OS/2 Requester in one of the following two ways: o Implicitly - Your application can implicitly load the OS/2 Requester either by linking with the import library BTRCALLS.LIB or by specifying imported functions in the application definition file. In either case, the operating system loads the OS/2 Requester automatically when the application is started. o Explicitly - Your application can load the OS/2 Requester explicitly using the operating system API functions. When the application loads the Requester explicitly, the operating system does not load the OS/2 Requester until notified to do so. Unloading the OS/2 Requester At an OS/2 workstation, the operating system removes the dynamic link routines from memory when the application terminates or when the application explicitly unloads the OS/2 Requester using the operating system API. NOTE: If files have been left open (as happens, for example, when an application does not issue a Close operation for each open file), simply logging out of one or more servers from a workstation does not close Btrieve files or terminate the Btrieve SPX connection to the server. To close files and terminate the connection, you must either unload the Requester or restart the workstation. Windows Requester In the Windows environment, you must load the DOS Requester, BREQUEST.EXE, before starting Windows. Windows-based Btrieve applications access the Requester by means of a DLL, WBTRCALL.DLL, which uses the DOS Protected Mode Interface (DPMI) that Windows provides. The Windows Requester (that is, WBTRCALL.DLL) is the Btrieve interface DLL for Windows v3.x. The DLL provides the same API as client-based Btrieve and requires no modification to the application. You can access local as well as remote files by running both client-based (local) Btrieve and the Requester at your workstation. If you want to run both client-based Btrieve and the Requester, you must run the Windows Conversion utility (WNDBCNVT.EXE) to convert the client-based WBTRCALL.DLL to WBTRLOCL.DLL. NOTE: Client-based Btrieve must be purchased separately. Windows Requester Configuration Options The following list describes the available configuration options for the Windows Requester. These options should be specified in the NOVDB.INI file under [brequestDPMI]. NOVDB.INI is the Novell initialization file for the Windows Requester. It is included on the distribution diskette. Tasks=# Specifies how many concurrent tasks may use the Windows Requester. The range is 1 through 255. The default value is 10. Local=Yes/No Instructs the Windows Requester to use client-based Btrieve for accessing files locally. The default value is No. Chkparms=Yes/No Instructs the Windows Requester to validate pointers passed to it. You should use this option only during development. The default is No. Loading the Windows Requester The DOS Requester must be loaded in the DOS environment before you start Windows. To load the DOS Requester, use the WINSTART.BAT file or type BREQUEST at the DOS prompt before loading Windows. An application may load the Windows Requester in one of the following two ways: o Implicitly - Your application can implicitly load the Windows Requester by either linking with the import library WBTRCALLS.LIB or by specifying imported functions in the application definition file. When an application loads a DLL implicitly, the operating system automatically loads the DLL when the application is started. o Explicitly - Your application may load the Windows Requester explicitly using the operating system API functions. The operating system does not load the DLL until notified to do so. NOTE: If you want to run a DOS Btrieve application in the DOS box and a Windows Btrieve application at the same time, you must have the DOS Requester loaded in each DOS session. However, if you have already loaded the DOS Requester before loading Windows, you cannot load the DOS Requester in any subsequent DOS session. Consequently, you cannot run the DOS Btrieve application in the DOS box. For Windows applications using the DOS Requester, load BREQUEST outside of Windows. In each Windows DOS session that will be running a Btrieve application, load BREQUEST with the /L option. Doing so will load another instance of BREQUEST that is available only to the DOS session. This operation provides the DOS session with its own copy of BREQUEST and prevents the DOS session from using the instance of BREQUEST that you loaded before starting Windows. Unloading the Windows Requester At a Windows workstation, the operating system removes the dynamic link routines from memory when the application terminates or when the application explicitly unloads the DLLs using the operating system API functions. NOTE: If Btrieve files are left open in an application because the application did not issue a Close operation, simply logging out of one or more servers from a workstation does not close the files or terminate the Btrieve SPX connection to the server. The files remain open until you restart the workstation or unload the DOS Requester using BREQUTIL -STOP. Also, keep in mind that a Reset operation closes files but does not unload the DOS Requester.